3D Graphics Programming with QuickDraw 3D 1.5.4

Registering a Custom Class

This section describes the routines that QuickDraw 3D provides to register and unregister custom object classes.

When a plug-in custom type is registered, its type parameter is allocated dynamically. Types are registered with Q3XObjectHierarchy_RegisterClass or Q3XElementClass_Register , or with the Q3XAttributeClass_Register routine as described in "Adding Application-Defined Attribute and Element Types" . In the case of Q3XObjectHierarchy_RegisterClass , the second parameter is the address of an object type--TQ3ObjectType , TQ3ElementType or TQ3AttributeType , depending on the call used for registration.

When your custom class uses a shared library, you should coordinate class registration with library registration. For more information, including sample code, see "Registering a Shared Library" .

Q3XObjectHierarchy_RegisterClass

You can use the Q3XObjectHierarchy_RegisterClass routine to register a class in the QuickDraw 3D hierarchy.



 
 TQ3XObjectClass Q3XObjectHierarchy_RegisterClass(

                     TQ3ObjectType     parentType,

                     TQ3ObjectType     *objectType,

                     char              *objectName,

                     TQ3MetaHandler    metaHandler,

                     TQ3MetaHandler    virtualMetaHandler,

                     unsigned long     methodsSize,

                     unsigned long     instanceSize);

parentType: The object type for which you want to create a subclass. The parent class must be currently registered with QuickDraw 3D. Pass in kQ3ObjectTypeInvalid (value 0) to create a subclass of the class TQ3Object .
objectType: On return, the object type of your subclass. This value is used as the binary type in a QuickDraw 3D metafiles. It is also returned in _GetType and Q3Object_GetLeafType calls and may be used in the Q3Object_IsType call.
objectName: The object name of your subclass. This C string must be unique among all registered classes in QuickDraw 3D, including parent classes. This value is used as the ASCII type in QuickDraw 3D metafiles.
metaHandler: A metahandler used to retrieve object methods and nonvirtual methods. This metahandler will be called repeatedly with a selector of type TQ3MethodType to retrieve methods for this object class. With some classes, this value will be NULL .
virtualMetaHandler: A metahandler used to retrieve virtual methods for your object and any of its subclasses. If you are registering a leaf class only, pass NULL . Classes that register as a subclass of this class will use the methods supplied here unless overridden by the subclass metahandlers. Methods that take a pointer to an object's private data should not be returned in this metahandler, as the methods only apply to the data in this class.
methodsSize: Indicates the size of any private class data in the class. If you are registering a leaf class only, pass 0. If you have private class data, a method of type kQ3MethodTypeObjectClassRegister must be registered to initialize the private data structure. A pointer to the structure is returned by Q3ObjectClass_GetClassPrivate or Q3Object_GetClassPrivate . If methodsSize is 0, these calls always return NULL .
instanceSize: The size of private instance data for your object. If this class has no instance data, this value may be 0. This would happen only if the class is used just abstractly to be subclassed or exists solely as a type. If a nonzero value is passed in, a method of type kQ3MethodTypeObjectNew must be registered to initialize the data. A pointer to the structure is returned by Q3Object_GetPrivate . If dataSize is 0, Q3Object_GetPrivate always returns NULL .

DESCRIPTION

The Q3XObjectHierarchy_RegisterClass routine registers the custom class detailed by its parameters. The object type is assigned at run time and returned to you in the objectType parameter. Often it is a good idea to store this type locally in a static variable, since it is used by many object system routines.

The Q3XObjectHierarchy_RegisterClass routine returns NULL if the class could not be registered.

SPECIAL CONSIDERATIONS

You should generally call Q3XObjectHierarchy_RegisterClass only in a function that has been registered by the Q3XSharedLibrary_Register call. Register the existence of this routine instead of calling it directly from a shared library registration routine.

EXAMPLE

The following is an example of a registration function, taken from the plug-in renderer sample in the QuickDraw 3D SDK. In this example the return value of the Q3XObjectHierarchy_RegisterClass function is stored in the global variable SRgRendererClass . To make this variable readily available to other code, it is declared static to the file in which the routine is implemented.



 
TQ3Status SR_Register(

    void)

{

    /* Create/register the class */

    SRgRendererClass = 

        Q3XObjectHierarchy_RegisterClass(

            kQ3SharedTypeRenderer,

            &SRgClassType,

            "SampleRenderer",

            SR_MetaHandler,

            NULL,

            0,

            sizeof(TSRPrivate));



 
    /* Make sure it worked */

    if (SRgRendererClass == NULL) {

        return (kQ3Failure);

    }



 
    return (kQ3Success);

}

Q3XObjectHierarchy_UnregisterClass

You can use the Q3XObjectHierarchy_UnregisterClass function to remove a custom object class registered with Q3XObjectHierarchy_RegisterClass.



 
TQ3Status Q3XObjectHierarchy_UnregisterClass (

                     TQX3ObjectClass objectClass);

objectClass: An object class.

DESCRIPTION

The Q3XObjectHierarchy_UnregisterClass function unregisters the custom object class specified by the objectClass parameter.

You should dispose of all instances of the custom object class you want to unregister before calling Q3XObjectHierarchy_UnregisterClass. If this is not done, Q3XObjectHierarchy_UnregisterClass returns kQ3Failure and the class remains registered.

You can also call Q3XObjectHierarchy_UnregisterClass to unregister a custom attribute type previously registered by the function Q3AttributeClass_Register .

SPECIAL CONSIDERATIONS

The best way to unload the class is by unloading the shared library, using the Q3XSharedLibrary_Unregister routine.

Q3ElementClass_Register

You can use the Q3ElementClass_Register function to register an application-defined element class.



 
TQ3ObjectClass Q3ElementClass_Register (

                     TQ3ElementType elementType, 

                     const char *name, 

                     unsigned long sizeOfElement, 

                     TQ3MetaHandler metaHandler);

elementType: An element type.
name: A pointer to a null-terminated string containing the name of the element's creator and the name of the type of element being registered.
sizeOfElement: The size of the data associated with the specified custom element type.
metaHandler: A pointer to an application-defined metahandler that QuickDraw 3D calls to handle the new custom element type.

DESCRIPTION

The Q3ElementClass_Register function returns, as its function result, an object class reference for a new custom element type having a type specified by the elementType parameter and a name specified by the name parameter. The metaHandler parameter is a pointer to the metahandler for your custom element type. See "Defining an Object Metahandler" for information on writing a metahandler. If Q3ElementClass_Register cannot create a new element type, it returns the value NULL .

The name parameter should be a pointer to null-terminated C string that contains your (or your company's) name and the name of the type of element you are defining. Use the colon character (:) to delimit fields within this string. The string should not contain any spaces or punctuation other than the colon character, and it cannot end with a colon. Here are some examples of valid creator names:



 
"MyCompany:SurfDraw:Wavelength"

"MyCompany:SurfWorks:VRModule:WaterTemperature"

The sizeOfElement parameter specifies the fixed size of the data associated with your custom element type. If you wish to associate dynamically sized data with your element type, put a pointer to a dynamically sized block of data into the set and have your handler's copy method duplicate the data. (In this case, you would set the sizeOfElement parameter to sizeof(Ptr) .) You also need to have your handler's dispose method deallocate any dynamically sized blocks.

Q3ElementType_GetElementSize

You can use the Q3ElementType_GetElementSize function to get the size of an application-defined element type.



 
TQ3Status Q3ElementType_GetElementSize (

                     TQ3ElementType elementType, 

                     unsigned long *sizeOfElement);

elementType: An element type.
sizeOfElement: On exit, the number of bytes occupied by an element of the specified element object class.

DESCRIPTION

The Q3ElementType_GetElementSize function returns, in the sizeOfElement parameter, the number of bytes occupied by an element of the type specified by the elementType parameter.